'\" t
.\"     Title: pklocalauthority
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: May 2009
.\"    Manual: pklocalauthority
.\"    Source: polkit
.\"  Language: English
.\"
.TH "PKLOCALAUTHORITY" "8" "May 2009" "polkit" "pklocalauthority"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pklocalauthority \- PolicyKit Local Authority
.SH "DESCRIPTION"
.PP
The Local Authority is the default PolicyKit authority implementation\&. Configuration for the Local Authority and information pertaining to authorization decisions are read from local files on the disk\&. One design goal of the Local Authority is to split configuration items into separate files such that 3rd party packages and users won\*(Aqt conflict trying to edit the same files\&. This policy also ensures smooth upgrades when distributing PolicyKit using a package management system\&.
.PP
Files shipped with PolicyKit and 3rd party packages (e\&.g\&. under package manager control) typically have comments (such as
\(lqDO NOT EDIT THIS FILE, it will be overwritten on update\(rq) telling the system administrator that changes will be overwritten on update\&.
.SH "ADMINISTRATOR AUTHENTICATION"
.PP
PolicyKit makes a distinction between
\fIuser authentication\fR
(to make the user in front of the system prove he really is the user) and
\fIadministrator authentication\fR
(to make the user in front of the system prove he really is an administrator)\&. Since various operating systems (or even flavors of the same operating system) has different ways of defining "administrator", the Local Authority provides a way to specify what "administrator authentication" means\&.
.PP
By default, "administrator authentication" is defined as asking for the root password\&. Since some systems, for usability reasons, don\*(Aqt have a root password and instead rely on a group of users being member of an administrative group that gives them super\-user privileges, the Local Authority can be configured to support this use\-case as well\&.
.PP
Configuration for the Local Authority is read from files in the
/etc/polkit\-1/localauthority\&.conf\&.d
directory\&. All files are read in lexigraphical order (using the C locale) meaning that later files can override earlier ones\&. The file
50\-localauthority\&.conf
contains the settings provided by the OS vendor\&. Users and 3rd party packages can drop configuration files with a priority higher than 60 to change the defaults\&. The configuration file format is simple\&. Each configuration file is a
\fIkey file\fR
(also commonly known as a
\fIini file\fR) with a single group called
[Configuration]\&. Only a single key,
AdminIdentities
is read\&. The value of this key is a semi\-colon separated list of identities that can be used when administrator authentication is required\&. Users are specified by prefixing the user name with
unix\-user:
and groups of users are specified by prefixing with
unix\-group:\&. See
the section called \(lqEXAMPLES\(rq
for an example of a configuration file\&.
.SH "DIRECTORY STRUCTURE"
.PP
The Local Authority reads files with
\&.pkla
extension from all directories located inside the
/etc/polkit\-1/localauthority
and
/var/lib/polkit\-1/localauthority
directories\&. By default, the following sub\-directories are installed\&.
.sp
.if n \{\
.RS 4
.\}
.nf
/etc/polkit\-1/
`\-\- localauthority
    |\-\- 10\-vendor\&.d
    |\-\- 20\-org\&.d
    |\-\- 30\-site\&.d
    |\-\- 50\-local\&.d
    `\-\- 90\-mandatory\&.d
    
.fi
.if n \{\
.RE
.\}
.PP
and
.sp
.if n \{\
.RS 4
.\}
.nf
/var/lib/polkit\-1/
`\-\- localauthority
    |\-\- 10\-vendor\&.d
    |\-\- 20\-org\&.d
    |\-\- 30\-site\&.d
    |\-\- 50\-local\&.d
    `\-\- 90\-mandatory\&.d
    
.fi
.if n \{\
.RE
.\}
.PP
The
/etc/polkit\-1/localauthority
hierarchy is inteded for local configuration and the
/var/lib/polkit\-1/localauthority
is intended for 3rd party packages\&.
.PP
Each
\&.pkla
file contains one or more authorization entries\&. If the underlying filesystem supports file monitoring, the Local Authority will reload information whenever
\&.pkla
files are added, removed or changed\&.
.PP
Each directory is intended for a specific audience
.PP
\fI10\-vendor\&.d\fR
.RS 4
Intended for use by the OS vendor\&.
.RE
.PP
\fI20\-org\&.d\fR
.RS 4
Intended for the organization deploying the OS\&.
.RE
.PP
\fI30\-site\&.d\fR
.RS 4
Intended for the site deploying the system\&.
.RE
.PP
\fI50\-local\&.d\fR
.RS 4
Intended for local usage\&.
.RE
.PP
\fI90\-mandatory\&.d\fR
.RS 4
Intended for the organization deploying the OS\&.
.RE
.PP
and new directories can be added/removed as needed\&.
.PP
As to regards to the content, each
\&.pkla
file is a standard
\fIkey file\fR
and contains key/value pairs in one or more groups with each group representing an authorization entry\&. A
\&.pkla
file MUST be named by using a scheme to ensure that the name is unique, e\&.g\&. reverse DNS notation or similar\&. For example, if the organization is
\(lqAcme Corp\(rq
needs to modify policy for the product
\(lqFrobnicator\(rq, a name like
com\&.acme\&.frobnicator\&.pkla
would be suitable\&.
.SH "AUTHORIZATION ENTRY"
.PP
Each group in a
\&.pkla
file must have a name that is unique within the file it belongs to\&. The following keys are are recognized:
.PP
\fIIdentity\fR
.RS 4
A semi\-colon separated list of globs to match identities\&. Each glob should start with
unix\-user:
or
unix\-group:
to specify whether to match on a UNIX user name or a UNIX group name\&.
.RE
.PP
\fIAction\fR
.RS 4
A semi\-colon separated list of globs to match action identifiers\&.
.RE
.PP
\fIResultActive\fR
.RS 4
The result to return for subjects in an active local session that matches one or more of the given identities\&. Allowed values are similar to what can be used in the
\fIdefaults\fR
section of
\&.policy
files used to define actions, e\&.g\&.
yes,
no,
auth_self,
auth_self_keep,
auth_admin
and
auth_admin_keep\&.
.RE
.PP
\fIResultInactive\fR
.RS 4
Like
\fIResultActive\fR
but instead applies to subjects in inactive local sessions\&.
.RE
.PP
\fIResultAny\fR
.RS 4
Like
\fIResultActive\fR
but instead applies to any subject\&.
.RE
.PP
\fIReturnValue\fR
.RS 4
A semi\-colon separated list of key/value pairs (of the form key=value) that are added to the details of authorization result on positive matches\&.
.RE
.PP
All keys specified above are required except that only at least one of
\fIResultAny\fR,
\fIResultInactive\fR
and
\fIResultActive\fR
must be present\&. The
\fIReturnValue\fR
key is optional\&.
.SH "EVALUATION ORDER"
.PP
When a Mechanism requests services from the Authority to check if a given Subject is authorized for a given Action, the authorization entries discussed above are consulted using the following algorithm\&.
.PP
The authorization entries from all \&.pkla files are ordered using the following rules\&. First all the basename of all sub\-directories (e\&.g\&.
\fI30\-site\&.d\fR) from both the
/etc/polkit\-1/localauthority
and
/var/lib/polkit\-1/localauthority
directories are enumerated and sorted (using the C locale)\&. If a name exists in both
/etc
and
/var, the one in
/etc
takes precedence\&. Then all
\&.pkla
files are read in order from this list of sub\-directories\&. For each
\&.pkla
file, authorizations from each file are appended in order resulting in an ordered list of authorization entries\&.
.PP
For example, given the following files
.sp
.if n \{\
.RS 4
.\}
.nf
/var/lib/polkit\-1
└── localauthority
    ├── 10\-vendor\&.d
    │   └── 10\-desktop\-policy\&.pkla
    ├── 20\-org\&.d
    ├── 30\-site\&.d
    ├── 50\-local\&.d
    ├── 55\-org\&.my\&.company\&.d
    │   └── 10\-org\&.my\&.company\&.product\&.pkla
    └── 90\-mandatory\&.d

/etc/polkit\-1
└── localauthority
    ├── 10\-vendor\&.d
    │   └── 01\-some\-changes\-from\-a\-subvendor\&.pkla
    ├── 20\-org\&.d
    ├── 30\-site\&.d
    ├── 50\-local\&.d
    ├── 55\-org\&.my\&.company\&.d
    │   └── 10\-org\&.my\&.company\&.product\&.pkla
    └── 90\-mandatory\&.d
    
.fi
.if n \{\
.RE
.\}
.PP
the evaluation order of the
\&.pkla
files is:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}

10\-desktop\-policy\&.pkla
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}

01\-some\-changes\-from\-a\-subvendor\&.pkla
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}

10\-org\&.my\&.company\&.product\&.pkla
(the
/var
one)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}

10\-org\&.my\&.company\&.product\&.pkla
(the
/etc
one)
.RE
.PP
When the list of authorization entries has been calculated, the authorization check can be made\&. First, the user of the Subject is determined and the groups that the user belongs are looked up\&. For each group identity, the authorization entries are consulted in order\&. If the authorization check matches the data from the authorization check, then the authorization result from
\fIRequireAny\fR,
\fIRequireInactive\fR
or
\fIRequireActive\fR
is used and
\fIReturnValue\fR
is added to the authorization result\&.
.PP
Finally, the authorization entries are consulted using the user identity in the same manner\&.
.PP
Note that processing continues even after a match\&. This allows for socalled
\(lqnegative authorizations\(rq, see
the section called \(lqEXAMPLES\(rq
for further discussion\&.
.SH "EXAMPLES"
.PP
The following
\&.conf
file
.sp
.if n \{\
.RS 4
.\}
.nf
[Configuration]
AdminIdentities=unix\-group:desktop_admin_r
    
.fi
.if n \{\
.RE
.\}
.PP
that any user in the
desktop_admin_r
UNIX group can be used for authentication when administrator authentication is needed\&. This file would typically be installed in the
/etc/polkit\-1/localauthority\&.conf\&.d
directory and given the name
60\-desktop\-policy\&.conf
to ensure that it is evaluted after the
50\-localauthority\&.conf
file shipped with PolicyKit\&. If the local administrator wants to override this (suppose
60\-desktop\-policy\&.conf
was shipped as part of the OS) he can simply create a file
99\-my\-admin\-configuration\&.conf
with the following content
.sp
.if n \{\
.RS 4
.\}
.nf
[Configuration]
AdminIdentities=unix\-user:lisa;unix\-user:marge
    
.fi
.if n \{\
.RE
.\}
.PP
to specify that only the users
lisa
and
marge
can authenticate when administrator authentication is needed\&.
.PP
The following
\&.pkla
file grants authorization to all users in the
staff
group for actions matching the glob
com\&.example\&.awesomeproduct\&.*
provided they are in an active session on the local console:
.sp
.if n \{\
.RS 4
.\}
.nf
[Normal Staff Permissions]
Identity=unix\-group:staff
Action=com\&.example\&.awesomeproduct\&.*
ResultAny=no
ResultInactive=no
ResultActive=yes
    
.fi
.if n \{\
.RE
.\}
.PP
If the users
homer
and
grimes
are member of the
staff
group but policy requires that an administrator needs to authenticate every time authorization for any action matching
com\&.example\&.awesomeproduct\&.*
is required, one would add
.sp
.if n \{\
.RS 4
.\}
.nf
[Exclude Some Problematic Users]
Identity=unix\-user:homer;unix\-user:grimes
Action=com\&.example\&.awesomeproduct\&.*
ResultAny=no
ResultInactive=no
ResultActive=auth_admin
    
.fi
.if n \{\
.RE
.\}
.PP
and make sure this authorization entry is after the first one\&.
.SH "AUTHOR"
.PP
Written by David Zeuthen
davidz@redhat\&.com
with a lot of help from many others\&.
.SH "BUGS"
.PP
Please send bug reports to either the distribution or the polkit\-devel mailing list, see the link
\m[blue]\fB\%http://lists.freedesktop.org/mailman/listinfo/polkit-devel\fR\m[]
on how to subscribe\&.
.SH "SEE ALSO"
.PP

\fBpolkit\fR(8)
